ElixirのライブラリをHexに公開する

#Elixir

かんあきひで

2016.10.18

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

人気のあるプログラミング言語には必ず良いライブラリがあります。
著名なLisp HackerでありY Combinatorの設立者であるポールグレアム氏は、エッセイ「人気の言語を作るには」で以下のように書いています。

型システムの設計みたいなことを考えるのが好きな言語設計者は身震いするかもしれない。ライブラリの設計だなんて、アプリケーションを書くみたいなことじゃないか! 残念でした。言語はプログラマのためのもので、プログラマが必要としているのはライブラリなのだ。

過激な意見ですが確かに一理ありますね。そして良いライブラリのある言語にはそれを支える優秀なパッケージマネージャが必ずあります。RubyのRubyGems, PealのCPAN, NodeJSのnpmなどです。
Elixir/ErlangにもHexというパッケージマネージャーがあります。

Hex

Hex.pm

今回は自作のライブラリをHexにリリースしてみます。

Hexのインストール

Hexをローカル環境にインストールします。
(Elixirのインストール方法はこのページを参考にしてください)

$ mix local.hex

ユーザー登録

以下コマンドでユーザー情報(ユーザー名、メールアドレス、パスワード)を登録します。

$ mix hex.user register

作成されたAPI keyは~/.hex/hex.configに保存されます

プロジェクト作成

登録するライブラリのプロジェクトを作成します。

mix new プロジェクト名

コードを書く

ここは好きなコードを皆さん書いてください。

メタデータの追加

ライブラリを公開する前に、説明とメタ情報を追加しましょう。mix.exsに追加します

defmodule Ehee.Mixfile do
  use Mix.Project  

  # ライブラリの説明を追加
  @description """
    Unofficial Elixir client for the Github API
  """
  
  def project do
    [app: :application_name, # ここは作成したプロジェクト名が設定されます
     version: "0.0.1",
     elixir: "~> 1.3",
     name: "Library Name", # この行にライブラリ名（プロジェクト名）を追加
     description: @description, # この行を追加
     package: package, # この行を追加
     build_embedded: Mix.env == :prod,
     start_permanent: Mix.env == :prod,
     deps: deps()]
  end

  # ライブラリのメタ情報を追加する
  defp package do
    [ maintainers: ["youraccountname"], # 先ほど登録したアカウント名
      licenses: ["MIT"], # 選択したライセンス
      links: %{ "Github" => "https://github.com/username/projectname" } # GitHubのリポジトリURL ]
  end

ライブラリを公開する

以下のコマンドでリリースしましょう

$ mix hex.publish

リリースはできたようですが、以下のメッセージが出力されドキュメントのリリースを促されます。

Don't forget to upload your documentation with `mix hex.docs`

ドキュメント

ライブラリのダウンロード

ex_docというドキュメント作成のためのライブラリと、earmarkというmarkdownからHTMLへ変換するライブラリをプロジェクトの依存ライブラリに追加しましょう。

  defp deps do
    [
      {:ex_doc, "~> 0.11"}, # この行を追加
      {:earmark, ">= 0.0.0"}, # この行を追加
    ]
  end

ダウンロードします。

$ mix deps.get

ドキュメントの追加

作成したライブラリのモジュールにドキュメントを追加しましょう。
モジュールの先頭には@moduledocでモジュールの説明を、メソッドには@doc でメソッドの説明を書きます。
以下のように追加します(既存のライブラリのソースで説明します)。

defmodule Ehee.Gists do
  import Ehee
  alias Ehee.Credential

  @moduledoc """  # ここにモジュールのドキュメントを追加する
  The Gist Webhooks API
  """

  @doc """  # ここにメソッドのドキュメントを追加する
  List authenticated users gists

  ## Example
      Ehee.Gists.list(credential)

  More info at: https://developer.github.com/v3/gists/#list-a-users-gists
  """
  @spec list(Credential.t) :: Ehee.response
  def list(credential) do
    get("/gists", credential)
  end
end